DELETED Markdown linting POC - #788
Conversation
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…iew points). Agent files point to these
…plify, de-dup, order, semantic line breaks)
Bumps [pymdown-extensions](https://github.com/facelessuser/pymdown-extensions) from 11.0 to 11.0.1. - [Release notes](https://github.com/facelessuser/pymdown-extensions/releases) - [Commits](facelessuser/pymdown-extensions@11.0...11.0.1) --- updated-dependencies: - dependency-name: pymdown-extensions dependency-version: 11.0.1 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com>
….claude/ and .github/templates/.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| # docs — same trust model as .claude/agents/*.md and .github/templates/*.md. They share a | ||
| # directory with human-facing docs (README.md, README-*.md), so scope this to the exact | ||
| # files rather than a directory cascade. | ||
| overrides: | ||
| - filter: | ||
| - AGENTS.md | ||
| - .github/workflows/AGENTS.md | ||
| config: | ||
| extends: ./.markdownlint-prompts.yaml | ||
| combine: replace |
There was a problem hiding this comment.
Please verify this block actually takes effect — I think it may be a silent no-op, for two independent reasons.
overrides/filter/combinedon't appear in the documented markdownlint-cli2 config properties I could check (config,customRules,fix,frontMatter,gitignore,globs,ignores,markdownItPlugins,modulePaths,noBanner,noInlineConfig,noProgress,outputFormatters,showFound).combine: replacein particular reads like ESLint/Prettier syntax rather than cli2's. If cli2 ignores unknown top-level keys, this parses fine and does nothing.- Even if it is supported, it fights this file's own header comment: "a plain
.markdownlint.*file in the same directory overrides this file'sconfigproperty". Root.markdownlint.yamlsits beside this file, so for root-levelAGENTS.mdthe discovered config should win over anything rule-related declared here..github/workflows/AGENTS.mdhas no directory config, so it also resolves to the root.markdownlint.yaml.
Cheap way to settle it: temporarily add a ```python fence to AGENTS.md and run uv run prek run markdownlint-cli2 --all-files. If MD040 doesn't fire, the override is inert. (I couldn't run the linter in my sandbox — no node/network — so this is unverified either way.)
If it turns out not to work, the per-file mechanism that's known-good at any cli2 version is an inline configure comment at the top of each AGENTS.md:
Downside is it duplicates the vocabulary instead of sharing .markdownlint-prompts.yaml, which loses the "adding a language is a trust decision made in one place" property. Worth the tradeoff discussion in the PR rather than picking silently.
| File links in historical chat messages now show as plain text instead of downloads. Chatbots and pipelines that use an assistant node still open and still run as before. See [Migrate Assistants](how-to/assistants_migration.md). | ||
|
|
||
| ## Sep 1, 2026 | ||
| * **NEW** An embedded widget channel can now require an **OAuth** token instead of its embed key, using the new **Credential mode** setting on the channel. In OAuth mode every request is validated against a token minted by your own backend, the embed snippet shown in Open Chat Studio includes a sample `authTokenProvider` implementation, and the widget must be on version 0.12.0 or later. Existing channels keep the embed-key mode they already have. Leaving the channel's allowed domains blank marks the channel as a server-only integration, so any request from a browser is refused. See [OAuth credential mode](chat_widget/reference.md#oauth-credential-mode). |
There was a problem hiding this comment.
This line is still over the new limit — it's between 651 and 669 characters (matches ^.{651,}$, not ^.{670,}$), so MD013 will fail here after the drop to 650. It's the only remaining offender I found across all tracked markdown outside docs/api/; the one other >650 hit is .claude/agents/documentation-pr-reviewer.md:3, which is inside YAML front matter and therefore excluded by default.
Splitting it after ...mode they already have. matches the sentence-boundary style used for the other three entries in this PR.
| # Line length — reduce progressively after long lines are fixed | ||
| MD013: | ||
| line_length: 750 | ||
| line_length: 650 |
There was a problem hiding this comment.
The ratchet needs a matching change on the producer side or it'll un-ratchet itself. docs/changelog.md is the file that keeps forcing this limit up, and most of its entries are written by the update-changelog workflow from .github/templates/changelog-instructions.md — which has no line-length guidance in its "General Changelog Guidelines" section. So the next automated changelog PR will land another single-line >650-char entry.
The PR description says "will use doc writer agents to keep lengths <650 in future", but the automation path doesn't go through those agents. One line in the template ("Wrap entries at sentence boundaries; keep each source line under 650 characters") would close it. Fine as a follow-up if you want to keep this PR small, but it's worth an issue rather than nothing.
Review: markdown linting extensionsThe trust-model reasoning in the description is sound, and extending it to Needs attention
Verified fine
Smaller notes
|
…rsed as part of "prompts"
…-type-contract exactly.
…y. Now markdown lint runs
… now consistent, Remvoe rule about line length
… references as this is not really needed
…Must not" column so less likely to drift
…t permissions to fetch code & run build & linting scripts.
…n how to add new providers on new Integration UI vs old UI
…d formatting with existing guidelines.
Matches the page's H1 rename from "Teams" to "Team Settings" earlier in this branch. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
[DevOps] Tighten workflow permissions (update-api-docs, update-confluence, ci
[Dev Tools] Ignore all CLAUDE.md files from markdown linting
[Docs] Team Settings UI: The new Integrations UI (phases 1-2)
Changelog + Docs: Add toggle filters, error count, and team display to notifications (OCS #4361)
…11.0.1 Bump pymdown-extensions from 11.0 to 11.0.1
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Changelog + Docs: Expose participant_data and session_state to evaluators (OCS #4312)
[AgentOps] Sync reviewer agent with writer's rules; expand to READMEs
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Changelog + Docs: refactor: remove the "Create from assistant" collection flow (OCS #4429)
….claude/ and .github/templates/.
…at-studio-docs into markdown-lint-fix
lisa-tarbo
changed the title
|
Decided to rather leave markdownlint configured as it is without special rules for AGENTS files |
3 participants
Background
Small enhancements to the markdown linting system
Continues with work done on this PR : #746
Details
Prompt files (.claude/agents/, .claude/commands/, .github/templates/, and now AGENTS.md) extend the base doc rules with two extra restrictions, both aimed at the same idea: a fenced code block's language tag is a trust signal, not syntax highlighting, since these files are read by Claude as instructions rather than rendered as docs for humans.
MD040 — restricted fence-language vocabulary. Regular docs can label a fence with any language. Prompt files are restricted to exactly three: markdown (a template of expected model output), bash (commands the model may run), and text (untrusted data interpolated into the prompt — never instructions). Adding a new language to this list is a trust decision about what that fence type means, not just a formatting fix.
MD046 — code blocks must be fenced, not indented. This closes a loophole in rule 1: an indented block carries no language label at all, so it could sidestep the vocabulary restriction entirely. Forcing every block to be a fence means every block has to declare what it is.
What not done